Skip to content

Bug, patch, and general forms use direct prompts - #21

Merged
Marius Storhaug (MariusStorhaug) merged 2 commits into
mainfrom
msx-intake-writing
Nov 11, 2026
Merged

Marius Storhaug (MariusStorhaug) merged 2 commits into
mainfrom
msx-intake-writing

Conversation

@MariusStorhaug

@MariusStorhaug Marius Storhaug (MariusStorhaug) commented Nov 4, 2026 •

Copy link
Copy Markdown
Member

The bug, patch, and general issue forms name the information that reporters give. Their prompts use direct instructions without filler or a promise of a fast response. Existing fields and submission requirements do not change.

Changed: Issue forms use direct input instructions

The bug form identifies expected and actual behavior, the environment, reproduction steps, related information, and evidence. The patch form asks for the existing content or behavior and the desired change. The general form asks for the issue subject and related information.

All three forms retain their names, titles, labels, field IDs, field order, types, and required flags. The bug form keeps three required and two optional textareas. The patch and general forms each keep one required textarea. Repositories that use these shared forms need no configuration change.


Technical details

Source and plan: Fresh preparation on 2026-11-11 verifies head deb2e80d65c1334a140c2f8c15eae738329542fb against live main base and merge base 0c67251812ea306543f3a14ab473ae357cfb76ac. Remote refs match. No source changes occur during this preparation; the worktree is clean. The draft opened after bug-form commit e3e59ac00134eaec301506e2f01492d90faead9b; the second small commit completes patch and general intake. All five delivery-plan steps are complete. #16 stays open until merge.

Before and after: All three introductions asked for "as much information as possible" and promised quick help. Each now states the information its form records. The field wording also becomes specific:

Field Before After
Bug description A clear and concise description of what the bug is vs. what you expected to happen. Give the expected behavior and the actual behavior.
Bug environment What version, commit, platform, or configuration were you using when the problem occurred? Give the version, commit, platform, or configuration in use when the problem occurred.
Patch description A clear and concise description of what you would want to change. Give the existing content or behavior and the change you want.
General description A clear and concise description. Give the subject of the issue and the related information.

The original pre-edit, one-time wording checks reported 3 values passing and 7 failing; all 10 passed after implementation. Fresh manual review covers all three forms, all 10 changed prose values, and the complete diff. It confirms the accepted requested-information meaning and direct en-US instructions. The environment prompt retains or; it does not require every listed environment value. No content decision remains.

Fresh lint provenance: This repository has no YAML lint configuration or installed hosted validation. Both fixed MSX docs source 1b0d4893c8fefabe604d04393068a8ff6f848082 and current source f9b335d0b78a3eead0b7efa573936e86cb1e7265 use Docs workflow blob de01a42b4c230de8b2c7540089cc15b945529a5b, with super-linter 4ce20838b8ab83717e78138c5b3a1407148e0918 and no YAML override. Its published default configuration, blob 2aa49bd1867e24acdea4172191922df6135b69c6, is saved unmodified outside source. Its dependency pin, blob 7ce0eabce1e3283119086a7ae179f2373fc00e13, matches installed yamllint 1.38.0. This is a pinned shared-validator default for local checks, not this repository's CI configuration. The installed default also matches upstream commit cba56bcde1fdd01c1deb3f945e69764c291a6530, blob b082e228469dd5909a6f58dd2466882e16d4ea87.

For each of the three base blobs and corresponding candidate files, the exact commands receive the original input bytes through stdin:

$shared = "$env:USERPROFILE\.copilot\session-state\73d907e5-c9b5-46c2-ab63-6404c149f36f\files\super-linter-4ce20838-yaml-default.yml"
python -m yamllint --config-file $shared -
python -m yamllint --strict --config-file $shared -
python -m yamllint --strict --config-data 'extends: default' -
Fresh verification Result
Pinned shared-validator default, normal and strict All 3 base and all 3 candidate files pass in both modes: 12 runs, exit 0, zero diagnostics. No published rule is weakened.
Explicit installed default, strict All 3 base and all 3 candidate files pass: 6 runs, exit 0, zero diagnostics.
PyYAML 6.0.3 complete contract comparison All 3 actual-base contracts match across 28 mappings, 6 sequences, and 122 scalar nodes. Exactly 10 prose values differ; all 112 other scalar nodes, key/field order, tags, styles, and comments are preserved.
Full input and routing contract All 7 textarea IDs, types, labels, and required flags match: 5 required and 2 optional. Form names, titles, top-level descriptions, labels, and routing match.
git diff --check Passed, exit 0.
git diff 0c67251812ea306543f3a14ab473ae357cfb76ac...deb2e80d65c1334a140c2f8c15eae738329542fb --check Passed, exit 0.
git diff --name-only 0c67251812ea306543f3a14ab473ae357cfb76ac...deb2e80d65c1334a140c2f8c15eae738329542fb Exactly the three owned forms: 01-bug.yml, 02-patch.yml, and 99-general.yml, under .github/ISSUE_TEMPLATE.

Native rendering and links: gh api --include --method POST markdown -H 'Accept: text/html' --input - sends each parsed introduction to GitHub with JSON mode: gfm and context: MSXOrg/.github. All 6 requests, covering 3 baseline and 3 candidate introductions, return HTTP 200. Each renders as one paragraph with complete visible text. The candidate bug and general introductions each contain one native <br>; patch has none. This is real Markdown rendering, not a simulated form or an issue-submission test. All 48 scalar string values across the candidate forms contain zero link targets, and native output contains zero links or images. Link verification is inapplicable, not a passing empty scan.

Standards and scope: The writing review uses the fixed MSX Documentation Model, Natural Language, Writing Guide, Markdown, Documentation, YAML, Testing, and applicable delivery guidance. The Writing Guide, official STE overview/FAQ, and locally verified Issue 9 support the review without a full STE-conformance claim. The native issue-form format remains intact.

Changed surface Standards checked Framework docs checked Result
.github/ISSUE_TEMPLATE/01-bug.yml Direct en-US prompts, preserved meaning, YAML Native GitHub issue-form format Fixed in this PR
.github/ISSUE_TEMPLATE/02-patch.yml Direct en-US prompts, preserved meaning, YAML Native GitHub issue-form format Fixed in this PR
.github/ISSUE_TEMPLATE/99-general.yml Direct en-US prompts, preserved meaning, YAML Native GitHub issue-form format Fixed in this PR

The feature form, config.yml, tests, validation tooling, README, contribution guidance, PR template, agent instructions, profile, security, and support files remain unchanged. The repository's fallback role and central-standards link remain correct. No maintained phrase/snapshot test, linter, dependency, workflow, label, ruleset, scheduler, or policy change is added. The original scoped convergence sweep found #16 and feature Task #14; the latter is not satisfied by this diff. Only #16 receives a closing reference.

Current reviews and protections: The current-head Copilot approval remains APPROVED. Fully paginated inspection finds zero inline comments, zero review threads, and no new PR comments. GitHub reports APPROVED, MERGEABLE, and CLEAN. gh pr checks reports no checks; the exact-head REST endpoint retains one successful historical review check and zero commit statuses. No hosted repository-validation result exists; the review check is not one.

Inherited active ruleset 19735160 requires squash-only PRs, stale-review dismissal, code-owner review, last-push approval, extra approval for unattributed changes, and thread resolution. No required-status-check rule is present. The classic protection endpoint's HTTP 404 does not remove these rules. No CODEOWNERS file exists at a supported location in the actual base. Copilot is the only approving account and its collaborator-permission response is none; native readiness metadata is not used as proof of an independently eligible last-push approval or as permission to bypass protection.

Lifecycle: The PR is open and non-draft under the later user-directed lifecycle change. GitHub auto-merge is null. Agent merge readback is enabled with merge_pr=false. The exclusive global merge slot remains with the root coordinator; no merge is attempted. Missing hosted CI remains disclosed. Operational exact-head local evidence does not install CI or waive an actual failing check.

The fresh issue evidence records the exact provenance, commands, results, and remaining authorization boundary. Full diagnostics, configuration bytes, ordered-tree comparison, and native HTML responses remain in local session artifacts, not in the repository. There is no source or access blocker.

Relevant issues (or links)

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approved

No active review issues are blocking the issue-form instruction updates.

No open issues 🎉

What changed in this PR

Updates the bug, patch, and general issue forms with direct input instructions so reporters know what information to provide.

Changes:

  • Replaces generic introductions with descriptions of each form’s purpose.
  • Clarifies prompts for bug details, requested changes, and general issues.
  • Preserves form fields, labels, required flags, and YAML structure.
File Description
.github/​ISSUE_TEMPLATE/​99-general.yml Clarifies the form’s scope and requests the issue subject and related information.
.github/​ISSUE_TEMPLATE/​02-patch.yml Requests existing content or behavior and the desired change.
.github/​ISSUE_TEMPLATE/​01-bug.yml Makes bug-report prompts direct and specifies the expected information.

Review effort: Balanced

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[documentation-writing-alignment] Use direct prompts in bug, patch, and general issue forms

2 participants